Java

You can integrate the Ditto SDK into Kotlin projects to develop for the Android platform.

For a complete overview of the platforms, transports, and devices the JavaScript SDK supports, select Java from the Directory of Compatibility Maps.

For the API reference, see ditto 4.7.1.

Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto.

• Android version 6.0 (Marshmallow)

• minSdk version 23

• compileSdk version 34

• Java Development Kit (JDK) version 11

Setting Up Your Environment

Include the Maven Central repository in your Gradle file, and then synchronize it with your project.

1. Confirm that mavenCentral() is in the project-level build.gradle:

   Bash

   allprojects {
       repositories {
           mavenCentral()
       }
   }
   

2. n the individual module build.gradle file:

   Bash

   dependencies {
     // ...
     implementation "live.ditto:ditto:4.+"
   }
   

Configuring Permissions

The Android operating system limits access to some device functionality for end-user control and privacy.

To fully unlock Ditto’s capabilities, configure your app to automatically request all necessary permissions from end users at runtime.

Android Manifest Permissions

The Ditto Android SDK includes a set of permissions that are required to use all the device features necessary to enable sync. The permissions below will be automatically merged into your app’s final manifest.

AndroidManifest.xml

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" tools:targetApi="s" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" android:usesPermissionFlags="neverForLocation" tools:targetApi="tiramisu" />

The tools:targetApi attribute causes the permission to only be requested on devices running the specified API level or higher. This avoids errors on older OS versions that do not recognize the permission.

The android:maxSdkVersion attribute causes that permission to only be requested on devices running the specified SDK level or lower. This avoids asking for more permissions than Ditto needs, however it will prevent your app from being able to request the permission on devices running a newer OS version. To opt out of this behavior and request the permission on all OS versions, see the following snippet:

AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:remove="android:maxSdkVersion" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:remove="android:maxSdkVersion" />

Note that you may need to add the xmlns:tools=“http://schemas.android.com/tools” namespace attribute to your app’s root <manifest>tag as shown in the AndroidManifest.xml example above.

This will configure your app’s build to ignore the android:maxSdkVersion attribute in our SDK allowing the permission to be requested on any SDK version. This techniquie can be used to tweak any permissions to your liking.

For more details, see the documentation for the Bluetooth and WiFi Aware permissions in the Android Documentation.

Runtime Permissions

Android requires certain permissions to be explicitly requested by the app to access features like Bluetooth Low Energy (LE) and Wi-Fi Aware. To comply, configure the manifest file for your app to request permissions from end users at runtime.

To improve the user experience for your app, request all necessary permissions at once by calling the DittoSyncPermissions helper in your Activity or Fragment’s onCreate method:

Java

void checkLocationPermission() {
   DittoSyncPermissions permissions = new DittoSyncPermissions(this);
   String[] missing = permissions.missingPermissions(permissions.requiredPermissions());
   if (missing.length > 0) {
      this.requestPermissions(missing, 0);
   }
}

On Android, after granting location access, Ditto may not immediately recognize the permission, causing a delay in syncing.

To address this, whenever a relevant permission changes, call refreshPermissions() to quickly check and start syncing with the new permissions.

Java

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
   super.onRequestPermissionsResult(requestCode, permissions, grantResults);
   this.ditto.refreshPermissions();
}

For more information about requesting permissions in a user-friendly way refer to Android’s documentation: Request App Permissions.

Integrating Ditto1

1. Add Ditto to your application.

   We recommend placing this in your Application.onCreate method. Note that the Context you want to reference here is the Application level Context, rather than whatever Activity you might happen to be instantiating the Ditto instance from initially. This is because you need to ensure that your app is keeping a single Ditto instance alive for the entire lifetime of the application so it’s not going out of scope or getting garbage collected.

   Java

   DittoDependencies androidDependencies = new DefaultAndroidDittoDependencies(this.context);
   DittoLogger.setMinimumLogLevel(DittoLogLevel.DEBUG);
   DittoIdentity identity = new DittoIdentity.OnlinePlayground(androidDependencies, "REPLACE_ME_WITH_YOUR_APP_ID", "YOUR_PLAYGROUND_TOKEN_HERE");
   Ditto ditto = new Ditto(androidDependencies, identity);
   
   try {
       ditto.startSync();
   } catch(DittoError e) {
       //handle error
   }
   

2. Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available in the portal.